home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / tex / tex31 / texbin.zoo / readme-e.inf < prev    next >
Encoding:
Text File  |  1991-07-19  |  17.3 KB  |  428 lines
  1. Info file: readme-e.inf,    -*-Text-*-
  2. produced by texinfo-format-buffer
  3. from file: readme-e.tex
  4.  
  5.  
  6. This file documents a TeX 3.1 and METAFONT 2.7 implementation for the
  7. Atari ST based on the WEB2C kit 5.8a from Karl Berry.
  8.  
  9. Copyright (C) 1990,1991 Frank Ridderbusch
  10.  
  11. Permission is granted to make and distribute verbatim copies of
  12. this manual provided the copyright notice and this permission notice
  13. are preserved on all copies.
  14.  
  15. Permission is granted to copy and distribute modified versions of this
  16. manual under the conditions for verbatim copying, provided also that
  17. the entire resulting derived work is distributed under the terms of a
  18. permission notice identical to this one.
  19.  
  20. Permission is granted to copy and distribute translations of this manual
  21. into another language, under the above conditions for modified versions.
  22.  
  23.  
  24.  
  25.  
  26. Preface
  27. =======
  28.  
  29. If you have already read earlier versions of this readme file, you can
  30. directly turn to the section "Dynamic memory allocation".
  31.  
  32. There is one important modification, I made, that I would like to
  33. mention just at the beginning. There are *no* files
  34. `initex.ttp' or `inimf.ttp' any longer, as there have been in
  35. earlier versions. I have merged the functions which are unique to
  36. `initex.ttp' or `inimf.ttp' into one executable (no big deal,
  37. only changing some defines). Therefore only the files `tex.ttp' and
  38. `mf.ttp' are in the archive. The specific `initex' or
  39. `inimf' functions (dumping) are selected by a commandline option.
  40. (See section `Installation and Usage')
  41.  
  42.  
  43. General Remarks
  44. ===============
  45.  
  46. This archive contains executables for the Atari ST. All executables
  47. were generated from the WEB and the WEB2C sources version 5.8a, which
  48. Karl Berry announced and released in a TeXhax digest, which appeared
  49. on my news site during November 1990.
  50.  
  51. The Atari executables were first compiled with the GNU C compiler
  52. v1.37.1 running in an Un*x cross-compiling environment. The resulting
  53. objects were then linked with the C-library (at patchlevel 58), which
  54. J.R.Bammi and E.R.Smith put together (Thanks to both of them for their
  55. good work). Later, after some additional minor changes, I recompiled the
  56. C sources with GCC v1.38 and maximum optimization at home on my ST,
  57. which is equipped with 2,5 meg. After obtaining GCC v1.40, the final
  58. recompilation took place with this version. The executables are
  59. currently linked with the library (version 8) from E.R.Smith, which he
  60. build for MiNT, his multitasking TOS extension. Additionally the archive
  61. contains a BigTeX version with very large buffers (for those of you,
  62. who have a Mega 4 ST and use very large macro packages).
  63.  
  64. If you don't have a cross compiling environment and want to recompile
  65. the sources, you can just as well convert the WEB sources to C on your
  66. local Un*x box and then carry the C sources home. If you want to do
  67. this, it a good idea to decrease the constant `MAXLINES' to `1000' in
  68. the file `src-5.8a/web2c/splitup.c'. After that, you should be able to
  69. compile all files.
  70.  
  71.  
  72. Implementation Details
  73. ======================
  74.  
  75. The files from the WEB2C kit required only very minor changes, mostly
  76. things concerning the slash as a path separator opposed to the backslash
  77. the Atari uses. TeX and METAFONT both discard any `\r' (Carriage Return)
  78. character before a `\n' (Newline) in the input of normal tex files (The
  79. everlasting difference between Un*x and other systems; `\n' versus
  80. `\r\n' as line separators). I also modified the programs `pltopf' and
  81. `vptovf' to ignore any `\r' characters. If you encounter any problems
  82. with error messages about illegal character in the input file, try at
  83. first to remove any `\r' characters before you investigate further. It
  84. should be trivial to write a small utility, which removes all `\r'
  85. characters from an input file.
  86.  
  87. TeX and METAFONT both passed the trip and the trap tests on the Atari.
  88.  
  89. METAFONT doesn't have any window support on the ST. (If someone would
  90. write a window interface for the ST, I would be very interested.) I
  91. don't mean a GEM interface with this remark. METAFONT has a
  92. rudimentary window interface, to display proof mode character on
  93. screen. The WEB2C kit provides support for X11, X10 and some others.
  94.  
  95. All executables will open any file in binary mode.
  96.  
  97.  
  98. Installation and Usage
  99. ======================
  100.  
  101. The complete TeX and METAFONT environment is controlled via
  102. environment variables ala Un*x. On my Atari I've set the following
  103. values (as an example under gulam):
  104.  
  105.      # All TeX font metric files are here.
  106.      setenv TEXFONTS f:\tex\texinput\tfm
  107.      # The dumped format files are found here.
  108.      setenv TEXFORMATS f:\tex\formats
  109.      # search paths for TeX input files
  110.      setenv TEXINPUTS .;f:\tex\texinput\latex\styles;f:\tex\texinput\macros
  111.      # The TeX string pool file is found here.
  112.      setenv TEXPOOL f:\tex
  113.      # The Metafont string pool file is found here.
  114.      setenv MFPOOL f:\metafont\mfbases
  115.      # The dumped base file is found here.
  116.      setenv MFBASES f:\metafont\mfbases
  117.      # search paths for Metafont input files
  118.      setenv MFINPUTS .;f:\metafont\mfinputs\cmr
  119.  
  120. (For a detailed description the above environment variables see the
  121. manual pages in the file `manpages.lzh', also available from the atari
  122. archive at terminator.)
  123.  
  124. The executables don't care about slashes or backslashes as path
  125. separators. Both can be used. Don't mind, that the string pool files are
  126. called `*.poo' instead of `*.pool''. The executables have no problems to
  127. find them.
  128.  
  129. The `initex' or `inimf' specific functions (dumping) are selected by
  130. giving the option `-i' as the last argument. Therefore to create the
  131. `plain.fmt' you have to issue the following commandline (assuming the
  132. environment variables are set correctly):
  133.  
  134.      tex 'plain \dump' -i
  135.  
  136. The same applies to METAFONT. As a sidenote, the `plain.fmt' file from
  137. the BigTeX is about 110 KB larger than the one from the normal TeX,
  138. which is about 168 KB in size. The absolute sizes vary depending on the
  139. sizes of the internal buffers.
  140.  
  141. Also the utility programs may search along some path for some files set
  142. by an environment variable. So, if one program complains about a file,
  143. that it can't find although it is in the current directory, prefix the
  144. filename with `./' ot `.\'.
  145.  
  146.  
  147. Dynamic Memory allocation for TeX
  148. =================================
  149.  
  150. The TeX versions dated later than March 2nd, 1991 have a dynamic
  151. memory allocation scheme for most of the large arrays. The startup
  152. message reflects this (TeX Version 3.1t2var). There are certainly better
  153. schemes, to achieve dynamic allocation, but I found, that the chosen
  154. approach required only very minimal changes to the source files.
  155.  
  156. Originally the header file `texd.h' (part of the sources) contained some
  157. defines for the values of `memmax', `memtop', `triesize' etc. I changed
  158. these defines into variables and also changed the dependent array
  159. declarations into pointer declarations. Now, before the main TeX code
  160. gets control, these pointer are initialized with malloced memory. Since
  161. I don't know, if there are any places in the code, which assume that
  162. uninitialized memory is cleared, the flag, which prevents TOS from
  163. clearing the whole TPA should not be set. This is to make really sure,
  164. that malloced memory is cleared. If you have a TOS version earlier than
  165. 1.4, you don't have to bother with this, since these version clear the
  166. whole memory with every program launch.
  167.  
  168. To be able to modify the size of the arrays in the executables, I
  169. borrowed the idea of the programs `fixstk.ttp' and `printstk.ttp', which
  170. come with the binary distribution of GNU-C for the ST. These two
  171. programs allow the modification or the display of the variable
  172. `stksize', which determines, how the stack and the memory is used by a
  173. program.
  174.  
  175.  
  176. TeX-CONF.TTP
  177. ============
  178.  
  179. I therefore wrote a program called `tex-conf.ttp', which allows the
  180. modification and the display of TeX's main configuration values. This
  181. works only if the executable is unstripped, because the information,
  182. which is present in the symbol table is used to locate the variables in
  183. the executable. Therefore you should never strip the TeX or METAFONT
  184. executables, or, if you do, then keep unstriped versions around.
  185.  
  186. A sample output of `tex-conf.ttp' is shown in the following lines,
  187. if it is invoked without any options (You also see the default
  188. configuration for the files as they are in the archive).
  189.  
  190.      f:\tex >> tex-conf bigtex.ttp tex.ttp mf.ttp
  191.  
  192.      TEX-CONF: The Configurator for TeX and METAFONT by fgth (Jul 18 1991)
  193.  
  194.      bigtex.ttp: TEXT segment is 190556 (187K)
  195.      bigtex.ttp: DATA segment is 1084 (2K)
  196.      bigtex.ttp: BSS segment is 239258 (234K)
  197.  
  198.      bigtex.ttp: bufsize is 3000 (3K)
  199.      bigtex.ttp: dvibufsize is 16384 (16K)
  200.      bigtex.ttp: fontmemsize is 50000 (196K)
  201.      bigtex.ttp: maxstrings is 7500 (30K)
  202.      bigtex.ttp: memmax is 131070 (512K)
  203.      bigtex.ttp: memtop is 131070 (0K)
  204.      bigtex.ttp: poolsize is 100000 (98K)
  205.      bigtex.ttp: savesize is 4000 (16K)
  206.      bigtex.ttp: stksize is 16384 (0K)
  207.      bigtex.ttp: triehash is 16000 (219K)
  208.      bigtex.ttp: triesize is 16000 (79K)
  209.  
  210.      bigtex.ttp: approx. memory usage running as INITEX 1624562 (1587K)
  211.      bigtex.ttp: approx. memory usage running as VIRTEX 1400562 (1368K)
  212.  
  213.      tex.ttp: TEXT segment is 197132 (193K)
  214.      tex.ttp: DATA segment is 1084 (2K)
  215.      tex.ttp: BSS segment is 69986 (69K)
  216.  
  217.      tex.ttp: bufsize is 500 (1K)
  218.      tex.ttp: dvibufsize is 4096 (4K)
  219.      tex.ttp: fontmemsize is 30000 (118K)
  220.      tex.ttp: maxstrings is 5000 (20K)
  221.      tex.ttp: memmax is 50000 (196K)
  222.      tex.ttp: memtop is 50000 (0K)
  223.      tex.ttp: poolsize is 45000 (44K)
  224.      tex.ttp: savesize is 1000 (4K)
  225.      tex.ttp: stksize is 16384 (0K)
  226.      tex.ttp: triehash is 12000 (165K)
  227.      tex.ttp: triesize is 12000 (59K)
  228.  
  229.      tex.ttp: approx. memory usage running as INITEX 889798 (869K)
  230.      tex.ttp: approx. memory usage running as VIRTEX 721798 (705K)
  231.  
  232.      mf.ttp: TEXT segment is 198472 (194K)
  233.      mf.ttp: DATA segment is 1112 (2K)
  234.      mf.ttp: BSS segment is 121894 (120K)
  235.  
  236.      mf.ttp: bufsize is 500 (1K)
  237.      mf.ttp: gfbufsize is 16384 (16K)
  238.      mf.ttp: maxstrings is 2000 (10K)
  239.      mf.ttp: memmax is 45000 (176K)
  240.      mf.ttp: memtop is 45000 (0K)
  241.      mf.ttp: poolsize is 32000 (32K)
  242.      mf.ttp: stksize is 16384 (0K)
  243.  
  244.      mf.ttp: approx. memory usage for METAFONT 560362 (548K)
  245.  
  246. First of all, the program prints the sizes of the TEXT, DATA and BSS
  247. segments of the executable. These values are found in the header of the
  248. program file. Then the current values of some variables are printed. The
  249. number of these variables differ depending on the file, which is
  250. currently examined. Most of these variables define the size of a memory
  251. array.
  252.  
  253. The variable `stksize' has the same meaning as in other GNU-C produced
  254. executables. It determines the usage of stack and memory.  `16k' means,
  255. that the executable will run on a 16 KB stack. This size works okay for
  256. me, but if you experience strange effect (bombs) while running TeX you
  257. might increase the value. Previously I had set `stksize' to `-1L', which
  258. would cause the program to grab every bit of memory it could get and do
  259. mallocs from internal heap. But that's not very nice in a multitasking
  260. environment (aka MiNT).
  261.  
  262. The variable `memtop' doesn't actually define a memory array, but it is
  263. presented, since it's value must be equal to `memmax', when the
  264. `tex.ttp' runs as INITeX (`-i' option). `memmax' may be larger than
  265. `memtop' for normal operation, but both (`memtop' and `memmax') may not
  266. be larger than 65530 for a normal sized TeX or METAFONT and not larger
  267. than 262140 for a BigTeX. The variable `triehash' is for information
  268. purposes only. The printed value is directly dependent on `triesize' and
  269. is only used when the memory usage for INITEX is calculated. INITEX uses
  270. 6 additional arrays for the handling of hyphenation pattern, which are
  271. all subsumed under the name `triehash'. The 6 additional arrays are also
  272. the reason, why an INITEX with static arrays is so much bigger than
  273. VIRTEX with the same sizes.
  274.  
  275. The other values directly define the size on an array. The values in
  276. braces show the actual memory, which is allocated for that array. The
  277. last line, that is printed, is the calculated memory usage, which is
  278. basically the sum of all shown arrays plus the TEXT-, DATA- and BSS
  279. segments sizes.
  280.  
  281.  
  282. Configuring TeX and METAFONT
  283. ============================
  284.  
  285. Now to change a value, you simple give the value name as an option
  286. during program invocation. For example:
  287.  
  288.      tex-conf -bufsize 2000 h:\tex\initex.ttp h:\tex\virtex.ttp
  289.  
  290. or
  291.  
  292.      tex-conf -memtop 50000 -memmax 50000 h:\tex\initex.ttp \ 
  293.          h:\tex\virtex.ttp
  294.  
  295. Changing a value makes it in most cases necessary to create new dumped
  296. formats with `tex -i' (*.FMT files).
  297.  
  298. I made all the above mentioned changes in the first place to get TeX
  299. also running on a 1 meg ST. For a 1 meg ST you might modify
  300. `dvibufsize', `memmax = memtop', and `triesize'. I was able to create
  301. *.FMT formats on a 1 meg ST (artificially achieved with a 1536 kb ram
  302. disk on my 2,5 meg ST) with `memmax = memtop = 50000', `triesize =
  303. 12000' and `dvibufsize = 4096', but I must admit there was nothing in
  304. memory except the hard disk driver and an environment setting program. A
  305. `triesize' of 12000 is necessary for german hyphenation pattern. If you
  306. only use English hyphenation pattern you can decrease `triesize' to
  307. 8000. This in turn might allow you to increase `memmax = memtop' to
  308. maximum. Remember, the main problem was initex with its 6 additional
  309. array for hyphenation compared with virtex. The increase of `triesize'
  310. by 1000 costs 15000 bytes of memory.
  311.  
  312. I've included the program `setenv.prg' and a file `env.inf' in the TeX
  313. executable archive. `setenv.prg' is an environment setter for the AES.
  314. `setenv.prg' goes into the auto folder and `env.inf' into the root
  315. directory of your boot drive.  `env.inf' is included as an example for a
  316. possible configuration.  I've included this program, to allow the
  317. invocation of TeX from the desktop.
  318.  
  319. Concluding this section, here is a short recipe to produce
  320. `plain.fmt' files on a 1 meg ST.
  321.  
  322.    * check, that `memmax = memtop = 50000', `triesize = 12000' and  
  323.      `dvibufsize = 4096'. (This is done with `tex-conf.ttp' running
  324.      from a CLI) 
  325.  
  326.    * edit `env.inf' to reflect your current setting.
  327.  
  328.    * copy `env.prg' to the auto folder and `env.inf' in root
  329.      directory of your boot drive.
  330.  
  331.    * strip the auto folder to the bare minimum to get maximum memory
  332.      (only your hard disk driver and `env.prg' should stay in place)
  333.  
  334.    * reboot your ST to activate the new auto folder setting.
  335.  
  336.    * invoke `tex.ttp' from the desktop with the arguments 
  337.      `plain \dump -i' or, if you start `tex.ttp' with only the
  338.      `-i' option, type `plain \dump', when TeX prompts with
  339.      `**' (This creates the `plain.fmt' file) 
  340.  
  341.    * repeat the above line if necessary for LaTeX.
  342.  
  343.    * reboot the ST with your old configuration.
  344.  
  345.    * Now you can now happily invoke `tex.ttp' from a CLI and become a
  346.      TeX wizard. 
  347.  
  348.  
  349. WARNING
  350. =======
  351.  
  352. The complete port is sort of a quick and dirty port.  I'm quite happy
  353. with the way it works, since I prefer a CLI environment like gulam. I'm
  354. also not a TeX or METAFONT wizard. I only compiled the sources. So, if
  355. you experience problems or have questions, which concerns TeX's or
  356. METAFONT's inner workings, DON'T write to me.  I won't be able to help
  357. you. Instead post an article in the news group `comp.text.tex'.
  358.  
  359. If you have Atari ST specific questions about this implementation,
  360. you CAN write to me.
  361.  
  362. If you are interested, I can also send a file containing the diffs
  363. relative to the files from Karl Berry (the original WEB2C kit), but I
  364. won't send the complete WEB and WEB2C sources.
  365.  
  366. Additionally you will need the latest versions of the various TeX and
  367. Metafont macro packages like Plain, LaTeX etc. Good places to look for
  368. these are the following archive sites:
  369.  
  370.    * [archive-server@]sun.soe.clarkson.edu: Email and anon ftp
  371.  
  372.    * [mail-server@]cs.ruu.nl: Email and anon ftp (for European users)
  373.  
  374.    * labrea.stanford.edu: anon ftp (The official TeX archive site)
  375.  
  376.    * [mailserv@]ymir.claremont.edu: Email and anon ftp
  377.  
  378.    * [mailserv@]rusmv1.rus.uni-stuttgart.de: Email and anon ftp (for
  379.      German users)
  380.  
  381.  
  382. Unsorted List of Changes
  383. ========================
  384.  
  385. The following is a list of differences between this TeX and METAFONT
  386. executables and the ones, which were available from the Atari archive at
  387. terminator during the end of 1990 until the middle of Jan 1991.
  388.  
  389.    * Changed the path separator from `:' to `;'. This change allows
  390.      the use of standard TOS path names (ex. `f:\tex'). Prior to this
  391.      you had to use the `/dev/<partition>' notation for path names. All
  392.      the utility programs still use this notation, since I didn't rebuild
  393.      them with the modified support files in the common directory.
  394.  
  395.    * Subdirectory search is enabled.
  396.  
  397.    * Upon startup a message is printed, when the executable was compiled.
  398.  
  399.    * Compiled with GNU-C v1.39 and maximum optimization (`-O',
  400.      `-fomit-frame-pointer', `-fcombine-regs'. The additional flag
  401.      `-fstrength-reduce' caused errors in the DVI file.)
  402.  
  403.    * Instead of ignoring all `\r' characters in the input stream, only
  404.      the `\r' from a `\r\n' pair is removed.
  405.  
  406. Change to the version compiled later than March 2, 1991
  407.  
  408.    * Dynamic memory allocation for most of the internal arrays.
  409.  
  410.    * Startup modified to reflect the dynamic allocation.
  411.  
  412.  
  413. Contacting me
  414. =============
  415.  
  416. You can contact either by electronic or snail mail.
  417.  
  418.      Email:
  419.      ridderbusch.kd@sni-usa.com    (America (North & South))
  420.      ridderbusch.kd@sni.de        (Rest of World)
  421.  
  422.      Snail:
  423.      Frank Ridderbusch
  424.      Sander Str. 17
  425.      W-4790 Paderborn
  426.      Germany
  427.  
  428.